✨ Add Quantum IPO Pass to mqt-cc - #1970

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@mlir/include/mlir/Dialect/QCO/Transforms/Passes.h`:
- Line 13: Add the mlir/IR/SymbolTable.h include to Passes.h so the SymbolTable
reference declaration is available from the header.
- Around line 37-40: Rename all ModuleOp parameters named module to moduleOp and
update every corresponding use: the three declarations in
mlir/include/mlir/Dialect/QCO/Transforms/Passes.h#L37-L40;
runAuxiliaryQubitHoisting and its uses in
mlir/lib/Dialect/QCO/Transforms/Optimizations/AuxiliaryQubitHoisting.cpp#L262-L280;
runQuantumFunctionBoundaryCommutation and its use in
mlir/lib/Dialect/QCO/Transforms/Optimizations/QuantumFunctionBoundaryCommutation.cpp#L102-L105;
runQuantumIPOPass and runCanonicalizerPass in
mlir/unittests/Dialect/QCO/Transforms/Optimizations/test_qco_quantum_ipo.cpp#L63-L77;
and runQuantumArgumentPromotion in
mlir/lib/Dialect/QCO/Transforms/Optimizations/QuantumArgumentPromotion.cpp#L315.
Keep declarations, definitions, and call behavior consistent while eliminating
shadowing of the module fixture.

In `@mlir/include/mlir/Dialect/QCO/Transforms/Passes.td`:
- Around line 309-312: Expand the `QuantumIPO` `description` to document its
four transformations: context-sensitive call specialization, quantum argument
promotion, auxiliary-qubit hoisting, and function-boundary commutation. Include
that it skips public functions, declarations, and recursive functions; depends
on the QCO convention matching each qubit result to the corresponding operand;
and runs `runQuantumFunctionBoundaryCommutation` exactly two times rather than
to a fixed point. Align the description indentation with neighboring pass
definitions.

In `@mlir/lib/Dialect/QCO/Builder/QCOProgramBuilder.cpp`:
- Around line 1485-1503: Validate function signatures eagerly in
QCOProgramBuilder.cpp: at lines 1485-1503, update call to compare
operands.getTypes() with funcOp.getArgumentTypes() and reportFatalUsageError
before linear-tracking updates; at lines 1450-1475, update endFunction to
compare returnValues.getTypes() with the enclosing function’s getResultTypes()
and reportFatalUsageError before creating func::ReturnOp.
- Around line 1385-1387: Update QCOProgramBuilder::getQubitTensorType to reject
size <= 0 with llvm::reportFatalUsageError, matching allocQubitRegister and
allocClassicalBitRegister, before constructing the RankedTensorType.
- Around line 1450-1475: Update endFunction to eagerly validate returnValues
against the resultTypes recorded by startFunction before creating
func::ReturnOp: reportFatalUsageError when the arity differs or any
corresponding value type differs from its declared result type. Keep the
existing qubit/tensor validation and cleanup checks, and perform this validation
at the endFunction call site before ReturnOp creation.
- Around line 1414-1419: In startFunction, check
SymbolTable::lookupSymbolIn(module, name) before func::FuncOp::create and reject
the operation when a function with the same name already exists. Preserve the
existing insertion point, function creation, and private visibility behavior for
unique names.

In `@mlir/lib/Dialect/QCO/IR/QCOOps.cpp`:
- Around line 485-507: Update the comments in QCOInlinerInterface to
consistently refer to the QCO dialect instead of the qc dialect, including all
four occurrences; leave the inlining behavior and method implementations
unchanged.

In `@mlir/lib/Dialect/QCO/Transforms/Optimizations/AuxiliaryQubitHoisting.cpp`:
- Around line 141-175: Replace the recursive traversal in isRecursiveHelper with
an iterative worklist or llvm::scc_iterator-based cycle check so recursion depth
cannot exhaust the stack. Preserve isRecursive’s behavior of detecting cycles
reachable from the function’s callees while continuing to avoid treating the
function as recursive solely through its initial node.
- Around line 177-182: Update tryAuxiliaryQubitHoisting to collect AllocOp
instances before erasing or otherwise mutating them, rather than modifying
operations during funcOp.walk. Apply the same collect-then-mutate approach for
func::ReturnOp handling, or preferably update return operands in place with
returnOp->setOperands(...) and avoid replacing or erasing the terminator; ensure
the return walk continues by closing the lambda loop instead of returning early.
- Around line 98-110: Update the call-handling logic around the visible
func::CallOp branch to avoid indexing results with an operand index: only
advance currentValue when a matching operand has a corresponding result, and
otherwise terminate or leave the traversal safely without accessing an
out-of-bounds result. Also handle the no-matching-operand case so the enclosing
while loop cannot repeat indefinitely, while preserving the existing linear
value propagation for valid operand/result pairs.
- Around line 262-285: Update runAuxiliaryQubitHoisting to rename its ModuleOp
parameter from module to moduleOp, remove the empty per-function
RewritePatternSet and applyPatternsGreedily call, and eliminate the
std::runtime_error throw. If reuse-qubit patterns remain required, populate and
apply them once after processing all hoistingCandidates, returning LogicalResult
on failure so QuantumIPO can call signalPassFailure; remove now-unused headers.

In `@mlir/lib/Dialect/QCO/Transforms/Optimizations/QuantumArgumentPromotion.cpp`:
- Around line 84-88: Update the user-traversal logic in canPromoteArgument to
reject unknown operations instead of following getResult(0) whenever a
single-result user is not explicitly recognized as preserving the qubit chain.
Mirror the existing unknown-user rejection used later in canPromoteArgument,
while retaining result-0 traversal only for supported operation types.
- Around line 283-303: Use the caller’s call-site location for all generated
promotion operations in this block: replace loc with callLoc when creating the
extract and insert operations, their ConstantIndexOp indices, and the
func::CallOp. Keep loc for callee-related processing and preserve the existing
operand and tensor transformation logic.
- Around line 229-246: Fix returnedQubits construction in the argument-promotion
flow so pass-through slots do not retain the erased extract result: build each
returned qubit after the rewiring/erasure using the surviving replacement value,
or substitute newArgs[i] directly when the insert scalar aliases the extract
result. Add a regression test covering a callee that extracts and immediately
reinserts an element without applying a gate.

In
`@mlir/lib/Dialect/QCO/Transforms/Optimizations/QuantumFunctionBoundaryCommutation.cpp`:
- Around line 23-25: Replace the std::unordered_map used by the quantum function
boundary optimization with an appropriate LLVM map container, preferably
llvm::StringMap, so lookups in the affected optimization logic accept StringRef
without creating temporary std::string keys. Update the associated include and
map access/types while preserving the existing key-value behavior.
- Around line 36-46: Update doOpsCancel to require both operations report
getNumQubits() == 1 before accepting the matching self-inverse gate types,
preserving the existing name and isa<XOp, YOp, ZOp, HOp> checks. This makes the
single-qubit contract explicit for the caller’s getInputQubit(0) usage.
- Around line 102-113: Rename the runQuantumFunctionBoundaryCommutation
parameter from module to moduleOp, and collect all func::CallOp values before
processing them. Replace the mutating module.walk processing with a two-phase
flow: gather calls using moduleOp, then iterate the collected calls and invoke
tryBoundaryCommutation so erasing operations cannot invalidate the walk.
- Around line 81-99: Key previousSpecializations by both the callee name and
parameter index so each cached specialization corresponds to the boundary gate
removed from that specific argument. Update the cache declaration and all
lookup, insertion, and access sites in the specialization flow around
copyFunction, preserving distinct redirected callees for different parameters.
Add a unit test covering one two-qubit callee specialized at separate call sites
for each parameter and verify both calls use the correct specialization.

In `@mlir/lib/Dialect/QCO/Transforms/Optimizations/QuantumIPO.cpp`:
- Around line 261-265: The specialization check in the function-name handling
around the visible funcOp logic is too broad and angle-insensitive. Remove the
funcOp.getName().contains(suffix) marker check and use a discardable attribute
on each cloned function to record the specific rotation specialization, reusing
rotationSpecializations’ name/operand/angle identity to distinguish different
angles and operands.
- Around line 280-285: Preserve and restore the shared PatternRewriter insertion
point around the update in the specialization routine containing newParameter
and the arith::ConstantOp. Save the current insertion point before
setInsertionPointToStart, perform constant creation and replacement, then
restore the saved point so trySpecializeZero and trySpecializePlus remain
independent of execution order.
- Around line 328-336: Update runOnOperation so it returns immediately after
signalPassFailure when applyPatternsGreedily fails, preventing subsequent
transformations from running on invalid IR. Remove the duplicated
runQuantumFunctionBoundaryCommutation call, keeping a single invocation with the
existing arguments.
- Around line 11-13: Remove the IDE-generated “Created by” comment at the top of
QuantumIPO.cpp, and add a concise top-level `@brief` documenting the purpose of
the quantum IPO pass, following the documentation style used in
QuantumArgumentPromotion.cpp.
- Around line 95-101: Update operationIsNopOnZero’s control lookup for CtrlOp to
use LLVM’s range-based llvm::is_contained helper with ctrl.getControlsIn()
instead of std::find and explicit iterators. Leave the existing zero-operation
checks and TODO marker unchanged.
- Around line 192-205: Update the loop around operationIsNopOnZero and the
newUser cast to handle ResetOp before accessing UnitaryOpInterface: replace the
reset output with its input qubit and erase the reset operation, then continue
the optimization safely. Alternatively, restrict this path to unitary users so
non-unitary operations are not cast or dereferenced.
- Around line 56-66: Update copyFunction to remove the unused PatternRewriter
parameter, insertion guard, and setInsertionPointAfter call; clone the function
and set its name directly while detached, then adjust all callers to use the new
signature before symbolTable.insert attaches the clone.

In
`@mlir/unittests/Dialect/QCO/Transforms/Optimizations/test_qco_quantum_ipo.cpp`:
- Around line 102-131: Add a QCO quantum IPO zero-specialization test alongside
specializeZeroArgumentDropsDiagonalGate where the callee’s leading operation is
reset on its qubit argument and the caller passes a freshly allocated qubit.
Build the reference with the original reset-containing callee retained and a
zero-argument specialization that forwards the argument without the reset, then
invoke and sink the specialized result to validate the ResetOp path.
- Around line 546-582: Add a separate promotion test alongside
promoteTensorArgumentToQubitArgument where the callee extracts element 0 from
its tensor argument and immediately re-inserts that same qubit without applying
a gate, returning only the rebuilt tensor. Build the reference with the promoted
qubit passed through directly, then preserve the caller’s
extract/call/insert/deallocate structure and verify with
expectModuleMatchesReference.

In `@src/qasm3/passes/TypeCheckPass.cpp`:
- Around line 378-388: In visitAssignmentStatement(), immediately after
evaluating the right-hand expression and obtaining exprTy, check exprTy.isError
and return before dereferencing exprTy.type. Preserve the existing assignment
type-checking flow for non-error inferred types, including results from
visitMeasureExpression().

In `@test/ir/test_qasm3_parser.cpp`:
- Line 209: Change the test declaration from sized `qubit[1] q;` to unsized
`qubit q;` so it exercises the `UnsizedTy::SingleQubit` path through the parser,
importer, and type checker, and add a separate measurement test case covering
that unsized qubit behavior.

---

Outside diff comments:
In `@mlir/lib/Dialect/QTensor/Utils/TensorIterator.cpp`:
- Around line 151-164: Update TensorIterator::tensor() to return nullptr when
the iterator is positioned at a func::ReturnOp, treating it as a no-OpResult
terminal operation like DeallocOp and the yield/condition operations. Preserve
the existing defining-operation handling and ensure forward()’s final-state
behavior remains unchanged.